openapi: 3.0.3
info:
  title: GigaChat API
  version: 1.0.0
  contact:
    name: GigaChat API
    url: 'https://developers.sber.ru/portal/products/gigachat-api'
    email: gigachat@sberbank.ru
  description: |
  
    Справочная документация по REST API нейросетевой модели GigaChat.

    О стоимости и условиях использования GigaChat API вы можете узнать в разделе [Тарифы и оплата](/ru/gigachat/api/tariffs).

    ## Получение токена доступа и авторизация запросов

    Запросы к GigaChat API авторизуются с помощью токена доступа по протоколу [OAuth 2.0](https://tools.ietf.org/html/rfc6749).
    Токен доступа передается в заголовке `Authorization`:
    
    ```sh
    curl -L -X GET 'https://gigachat.devices.sberbank.ru/api/v1/models' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer <токен_доступа>'
    ```

    Чтобы получить токен, отправьте запрос [POST /api/v2/oauth](/ru/gigachat/api/reference/rest/post-token):

    ```sh
    curl -L -X POST 'https://ngw.devices.sberbank.ru:9443/api/v2/oauth' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Accept: application/json' \
    -H 'RqUID: <идентификатор_запроса>' \
    -H 'Authorization: Basic <авторизационные_данные>' \
    --data-urlencode 'scope=GIGACHAT_API_PERS'
    ```

    Где:

    * `RqUID` — обязательный заголовок, в котором нужно передать уникальный идентификатор запроса в формате `uuid4`.
    * `Authorization` — обязательный заголовок, в котором нужно передать авторизационные данные — строку, полученную в результате кодирования в base64 идентификатора (Client ID) и клиентского ключа (Client Secret) API.
    * `scope` — обязательное поле в теле запроса, которое указывает к какой версии API выполняется запрос. Возможные значения:
      * `GIGACHAT_API_PERS` — доступ для физических лиц.
      * `GIGACHAT_API_CORP` — доступ для ИП и юридических лиц.

    При успешном выполнении запроса GigaChat API вернет токен доступа, который действует в течение 30 минут:

    ```json
    {
      "access_token": "eyJhbGci3iJkaXIiLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIn0..Dx7iF7cCxL8SSTKx.Uu9bPK3tPe_crdhOJqU3fmgJo_Ffvt4UsbTG6Nn0CHghuZgA4mD9qiUiSVC--okoGFkjO77W.vjYrk3T7vGM6SoxytPkDJw",
      "expires_at": 1679471442
    }
    ```

    :::note

    Как получить токен и авторизационные данные (Client Id и Client Secret) читайте в разделах [Быстрый старт для физических лиц](/ru/gigachat/individuals-quickstart) и [Быстрый старт для ИП и юридических лиц](/ru/gigachat/legal-quickstart).

    :::

servers:
- url: https://gigachat.devices.sberbank.ru/api/v1
tags:
- name: Авторизация
  description: Получение токена доступа для авторизации запросов.
- name: Модели
  description: Запросы для получения данных доступных моделей.
- name: Чат
  description: Обмен сообщениями с моделью и информация о лимите токенов.
- name: Файлы
  description: В разделе описаны методы для работы с файлами с помощью GigaChat.
paths:
  /oauth:
    post:
      tags:
        - Авторизация
      servers:
        - url: https://ngw.devices.sberbank.ru:9443/api/v2
      parameters:
        - name: RqUID
          in: header
          description: |
            Уникальный идентификатор запроса. Соответствует формату [`uuid4`](https://www.uuidgenerator.net/version4).

            Параметр для журналирования входящих вызовов и разбора инцидентов.
            Для создания уникального идентификатора можно использовать стандартные библиотеки и классы для генерации UUID и GUID.

            Пример: `6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e`.
          required: true
          schema:
            type: string
            format: uuid
            pattern: (([0-9a-fA-F-])36)
            example: 6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e
      requestBody:
         content:
            'application/x-www-form-urlencoded':
              schema:
               type: object
               properties:
                  scope: 
                    description: |
                      Версия API. Возможные значения:

                      * `GIGACHAT_API_PERS` — доступ для физических лиц.
                      * `GIGACHAT_API_CORP` — доступ для юридических лиц.
                    type: string
                    enum:
                      - GIGACHAT_API_PERS
                      - GIGACHAT_API_CORP
                    example: GIGACHAT_API_PERS
               required:
                 - scope
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - Базовая аутентификация: [client_id, client_secret]
      operationId: postToken
      summary: Получить токен доступа
      description: |
        Возвращает токен доступа для авторизации запросов к API.
        Токен доступа действителен в течение 30 минут.

        В заголовке `Authorization` нужно передать авторизационные данные — строку, полученную в результате кодирования в base64 идентификатора (Client ID) и клиентского ключа (Client Secret) API.

        Консоль запросов автоматически кодирует заданные идентификатор и клиентский ключ.

        :::note

        Как получить токен и авторизационные данные (Client Id и Client Secret) читайте в разделах [Быстрый старт для физических лиц](/ru/gigachat/individuals-quickstart) и [Быстрый старт для ИП и юридических лиц](/ru/gigachat/legal-quickstart).

        :::
  /tokens/count:
    post:
      tags:
      - Чат
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokensCountBody'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokensCount'
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - Токен доступа: []
      operationId: postTokensCount
      summary: Подсчитать количество токенов
      description: Возвращает объект с информацией о количестве токенов, подсчитанных заданной моделью в строках. Строки передаются в массиве `input`.
  /models:
    get:
      tags:
        - Модели
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models'
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - Токен доступа: []
      operationId: getModels
      summary: Получить список моделей
      description: Возвращает массив объектов с данными доступных моделей. Описание доступных моделей в разделе [Модели GigaChat](/ru/gigachat/models).
  /files/{file_id}/content:
    get:
      tags:
        - Файлы
      parameters:
        - name: file_id
          description: |
            Идентификатор созданного изображения, полученный в ответ на запрос пользователя.
            Содержится в ответе модели, в теге `<img>`, в аттрибуте `src`.

            Побробнее в разделе [Генерация изображений](/ru/gigachat/api/images-generation).
          schema:  
            type: string
          in: path
          required: true
      responses:
        '200':
          content:
            application/jpg: {}
          description: OK
        '400':
          description: Invalid model ID
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NoSuchModel'
      security:
        - Токен доступа: []
      operationId: getFileId
      summary: Получить изображение по идентификатору
      description: |
        Возвращает файл изображения в бинарном представлении, в формате JPG.

        Изображения создаются с помощью запроса [POST /chat/completions](/ru/gigachat/api/reference/rest/post-chat).

        Подробнее читайте в разделе [Генерация изображений](/ru/gigachat/api/images-generation).
        
        :::note

        Консоль запроса отключена из-за бинарного формата ответа.

        :::
  /chat/completions:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Chat'
      tags:
        - Чат
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletion'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequestFormat'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NoSuchModel'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - Токен доступа: []
      operationId: postChat
      summary: Получить ответ модели на сообщения
      description: Возвращает ответ модели с учетом переданных сообщений.
  /embeddings:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingsBody'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Embedding'
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - Токен доступа: []
      operationId: postEmbeddings
      summary: Создать эмбеддинг
      description: |
        Возвращает векторные представления соответствующих текстовых запросов. Индекс объекта с векторным представлением (поле `index`) соответствует индексу строки в массиве `input` запроса.

        Векторное представление выглядит как массив чисел `embedding`. Каждое значение в массиве представляет одну из характеристик или признаков текста, учтенных при вычислении эмбеддинга. Значения образуют числовое представление текста и позволяют анализировать и использовать текст в различных задачах. Как правило, чем ближе значения эмбеддингов друг к другу, тем более семантически близки тексты.
components:
  schemas:
    Model:
      type: object
      properties:
        id:
          description: Название модели. Описание доступных моделей смотрите в разделе [Модели GigaChat](/ru/gigachat/models).
          type: string
          enum:
            - GigaChat
            - GigaChat:latest
            - GigaChat-Plus
            - GigaChat-Pro
          example: GigaChat
        object:
          description: Тип сущности в ответе, например, модель
          type: string
          example: model
        owned_by:
          description: Владелец модели
          type: string
          example: salutedevices
    ModelId:
      type: object
      properties:
        model:
          $ref: '#/components/schemas/Model/properties/id'
    Models:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        object:
          description: Тип сущности в ответе, например, список.
          type: string
          example: list
    FileId:
      required:
        - file_id
      type: object
      properties:
        file_id:
          description: |
            Идентификатор созданного изображения, полученный в ответ на запрос пользователя.
            Содержится в ответе модели, в теге `<img>`, в аттрибуте `src`.

#            Побробнее в разделе [Генерация изображений](/ru/gigachat/api/images-generation).
          type: string
          example: 7wy0e9934sbjc09snz40c2gf1mej42ra0r00d8yz4d47r0adb17281t3096qpnamb4eqc1t3bd7qj1jman5q2mtzawfqrmgtbd7dv2bx54
    Chat:
      required:
        - model
        - messages
      type: object
      properties:
        model:
          $ref: '#/components/schemas/Model/properties/id'
        messages:
          type: array
          description: Массив сообщений, которыми пользователь обменивался с моделью.
          items:
            $ref: '#/components/schemas/message'
        function_call:
          description: |
            Поле которе отвечает за то, как GigaChat будет [работать с функциями](/ru/gigachat/api/function-calling).
            Может быть строкой или объектом.

            Возможные значения:

            * `none` — режим работы по умолчанию. Если запрос не содержит `function_call` или значение поля — `none`, GigaChat не вызовет функции, а просто сгенерирует ответ в соотвествии с полученными сообщениями;

            * `auto` — в зависимости от содержимого запроса, модель решает сгенерировать сообщение или вызвать функцию.
            Модель вызывает встроенные функции, если отсутствует массив `functions` с описанием пользовательских функций.
            Если запрос содержит `"function_call": "auto"` и массив `functions` с описанием пользовательских функций, модель будет генерировать аргументы для описанных функций и не сможет вызвать встроенные функции независимо от содержимого запроса;
            
            * `{"name": "название_функции"}` — принудительная генерация аргументов для указанной функции. Вы можете явно задать часть аргументов с помощью объекта `partial_arguments`. Остальные аргументы модель сгенерирует самостоятельно. При принудительной генерации, массив `functions` обязан содержать объект с описанием указанной функции. В противном случае вернется ошибка.
          oneOf:
            - $ref: '#/components/schemas/function_call_custom_function'
            - $ref: '#/components/schemas/function_call_none_auto'
        functions:
          type: array
          description: Массив с описанием пользовательских функций.
          items:
            type: object
            required:
              - "name"
              - "parameters"
            properties:
              name:
                type: string
                description: Название пользовательской функции, для которой будут сгенерированы аргументы.
                example: pizza_order
              description:
                type: string
                description: Текстовое описание функции.
                example: Функция для заказа пиццы
              parameters:
                type: object
                properties: {}
                description: Валидный JSON-объект с набором пар ключ-значение, которые описывают аргументы функции.
              few_shot_examples:
                type: array
                description: |
                  Объекты с парами `запрос_пользователя`-`параметры_функции`, которые будут служить модели примерами ожидаемого результата.
                items:
                  type: object
                  required:
                    - "request"
                    - "params"
                  properties:
                    request:
                      type: string
                      description: Запрос пользователя.
                      example: Погода в Москва в ближайшие три дня
                    params:
                      type: object
                      description: Пример заполнения параметров пользовательской функции.
                      properties: {}
              return_parameters:
                type: object
                description: JSON-объект с описанием параметров, которые может вернуть ваша функция.
                properties: {}
        temperature:
          format: float
          type: number
          description: |
            Температура выборки. Значение температуры должно быть не меньше ноля. Чем выше значение, тем более случайным будет ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.

            Значение по умолчанию зависит от выбранной модели (поле `model`) и может изменяться с обновлениями модели.
          minimum: 0
          example: 1.0
        top_p:
          format: float
          type: number
          description: |
            Параметр используется как альтернатива температуре (поле `temperature`). Задает вероятностную массу токенов, которые должна учитывать модель.
            Так, если передать значение 0.1, модель будет учитывать только токены, чья вероятностная масса входит в верхние 10%.

            Значение по умолчанию зависит от выбранной модели (поле `model`) и может изменяться с обновлениями модели. Значения изменяются в диапазоне от ноля до единицы включительно.

            Значение изменяется в диапазоне от 0 до 1.
          minimum: 0
          maximum: 1
          example: 0.1
        n:
          description: |
            Количество вариантов ответов, которые нужно сгенерировать для каждого входного сообщения.

            Количество вариантов может изменяться от одного до четырех. По умолчанию модель возвращает один вариант ответа.
          format: int64
          type: integer
          minimum: 1
          maximum: 4
          default: 1
          example: 1
        stream:
          type: boolean
          description: |
            Указывает, что сообщения надо передавать по частям в потоке.

            Сообщения передаются по протоколу [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format).

            Поток завершается событием `data: [DONE]`.

            Подробнее читайте в разделе [Потоковая передача токенов](/ru/gigachat/api/response-token-streaming).
          default: false
          example: false
        max_tokens:
          description: Максимальное количество токенов, которые будут использованы для создания ответов.
          format: int64
          type: integer
          default: 1024
          example: 512
        repetition_penalty:
          type: number
          format: float
          description: |
            Количество повторений слов:
            
            * Значение 1.0 — нейтральное значение.
            * При значении больше 1 модель будет стараться не повторять слова.

            Значение по умолчанию зависит от выбранной модели (поле `model`) и может изменяться с обновлениями модели.
          example: 1.0
        update_interval:
          type: number
          description: |
            Параметр потокового режима (`"stream": "true"`).
            Задает минимальный интервал в секундах, который проходит между отправкой токенов.
            Например, если указать `1`, сообщения будут приходить каждую секунду, но размер каждого из них будет больше, так как за секунду накапливается много токенов.
          default: 0
          example: 0
    message:
      type: object
      properties:
        role:
          type: string
          description: |
            Роль автора сообщения:

            * `system` — системный промпт, который задает роль модели, например, должна модель отвечать как академик или как школьник;
            * `assistant` — ответ модели;
            * `user` — сообщение пользователя;
            * `function` — сообщение с результатом работы [пользовательской функции](/ru/gigachat/api/function-calling#rabota-s-sobstvennymi-funktsiyami). В сообщении с этой ролью передавайте в поле `content` валидный JSON-объект с результатами работы функции.

            Для сохранения контекста диалога с пользователем передайте несколько сообщений. Подробнее читайте в разделе [Работа с историей чата](/ru/gigachat/api/keeping-context).
          enum:
            - system
            - user
            - assistant
            - function
          example: user
        content:
          description: |
            Содержимое сообщения. Зависит от роли.

            Если поле передается в сообщении с ролью `function`, то в нем указывается валидный JSON-объект с аргументами функции, указанной в поле `function_call.name`.

            В остальных случаях содержит либо системный промпт (сообщение с ролью `system`), либо текст сообщения пользователя или модели.
        data_for_context:
          $ref: '#/components/schemas/MessagesRes/properties/data_for_context'
    MessagesRes:
      type: object
      description: Сгенерированное сообщение.
      properties:
        role:
          type: string
          enum:
            - assistant
            - function_in_progress
          description: |
            Роль автора сообщения.

            Роль `function_in_progress` используется при работе встроенных функций в режиме [потоковой передачи токенов](/ru/gigachat/api/function-calling#potokovaya-peredacha-tokenov).
          example: assistant
        content:
          type: string
          description: |
            Содержимое сообщения, например, результат генерации.

            В сообщениях с ролью `function_in_progress` содержит информацию о том, сколько времени осталось до завершения работы встроенной функции.
          example: 'Здравствуйте! К сожалению, я не могу дать точный ответ на этот вопрос, так как это зависит от многих факторов. Однако обычно релиз новых функций и обновлений в GigaChat происходит постепенно и незаметно для пользователей. Рекомендую следить за новостями и обновлениями проекта в официальном сообществе GigaChat или на сайте разработчиков.'
        data_for_context:
          type: array
          items:
            type: object
            properties: {}
          description: |
            Массив сообщений, описывающих работу [встроенных функций](/ru/gigachat/api/function-calling#vyzov-vstroennykh-funktsiy).

            Для сохранения контекста, обязательно передавайте массив в запросе на генерацию, в сообщении с ролью `assistant`.
    Usage:
      type: object
      description: Данные об использовании модели.
      properties:
        prompt_tokens:
          format: int32
          description: Количество токенов во входящем сообщении (роль `user`).
          type: integer
          example: 18
        completion_tokens:
          format: int32
          description: Количество токенов, сгенерированных моделью (роль `assistant`).
          type: integer
          example: 68
        total_tokens:
          format: int32
          description: Общее количество токенов.
          type: integer
          example: 86
        system_tokens:
          format: int32
          description: Количество токенов в системном промпте (роль `system`).
          type: integer
          example: 86
    ChatCompletion:
      type: object
      properties:
        choices:
          type: array
          description: Массив ответов модели.
          items:
            $ref: '#/components/schemas/Choices'
        created:
          format: int64
          type: integer
          description: Дата и время создания ответа в формате Unix time.
          example: 1678878333
        model:
          $ref: '#/components/schemas/Model/properties/id'
        usage:
          $ref: '#/components/schemas/Usage'
        object:
          type: string
          description: Название вызываемого метода.
          example: chat.completion
    Choices:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/MessagesRes' 
           
        index:
          format: int32
          type: integer
          description: Индекс сообщения в массиве начиная с ноля.
          example: 0
        finish_reason:
          description: |
            Причина завершения гипотезы. Возможные значения:
            
            * `stop` — модель закончила формировать гипотезу и вернула полный ответ;
            * `length` — достигнут лимит токенов в сообщении;
            * `function_call` — указывает что при запросе была вызвана встроенная функция или сгенерированы аргументы для пользовательской функции;
            * `blacklist` — запрос подпадает под [тематические ограничения](/ru/gigachat/limitations#tematicheskie-ogranicheniya-zaprosov).
            
          type: string
          enum:
            - stop
            - length
            - function_call
            - blacklist
          example: "stop"
    Token:
      type: object
      properties:
        Токен доступа:
          type: string
          description: Токен для авторизации запросов.
          example: >-
            eyJhbGci3iJkaXIiLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIn0..Dx7iF7cCxL8SSTKx.Uu9bPK3tPe_crdhOJqU3fmgJo_Ffvt4UsbTG6Nn0CHghuZgA4mD9qiUiSVC--okoGFkjO77W.vjYrk3T7vGM6SoxytPkDJw
        expires_at:
          format: int64
          description: Дата и время истечения действия токена в формате Unix time.
          type: integer
          example: 1679471442
    TokensCount:
      type: array
      items:
        type: object
        properties:
          object:
            type: string
            description: Описание того, какая информация содержится в объекте.
            default: tokens
          tokens:
            type: integer
            description: Количество токенов в соответствующей строке.
            example: 7
          characters:
            type: integer
            description: Количество символов в соответствующей строке.
            example: 36
    Embedding:
      type: object
      required:
        - "data"
        - "object"
      properties:
        object:
          type: string
          description: Формат структуры данных.
          default: list
        data:
          type: array
          items:
            type: object
            description: Объект с данными о векторном представлении текста.
            required:
              - "object"
              - "embedding"
              - "index"
              - "usage"
            properties:
              object:
                type: string
                description: Тип объекта.
                default: embedding
              embedding:
                type: array
                description: Массив чисел, представляющих значения эмбеддинга для предоставленного текста. 
                items:
                  type: integer
                  format: float
              index:
                type: integer
                description: Индекс соответствующий индексу текста, полученного в массиве `input` запроса.
                example: 0
              usage:
                type: object
                properties:
                  prompt_tokens:
                    type: number
                    description: Количество токенов в строке, для которой сгенерирован эмбеддинг.
                    example: 6
        model:
          type: string
          description: Название модели, которая используется для вычисления эмбеддинга.
          example: Embeddings
    TokensCountBody:
      type: object
      required:
        - "model"
        - "input"
      properties:
        model:
          type: string
          description: Название модели, которая будет использована для подсчета количества токенов.
          example: GigaChat
        input:
          type: array
          description: Строка или массив строк, в которых надо подсчитать количество токенов.
          items:
            type: string
            example: Я к вам пишу — чего же боле?
    EmbeddingsBody:
      type: object
      required:
        - "input"
      properties:
        model:
          type: string
          description: Название модели, которая будет использована для создания эмбеддинга.
          default: Embeddings
        input:
          type: array
          description: Строка или массив строк, которые будут использованы для генерации эмбеддинга.
          items:
            type: string
            example: Расскажи о современных технологиях
    function_call_custom_function:
      type: object
      properties:
        name:
          type: string
          description: Название функции.
          example: sbermarket-pizza_order
        partial_arguments: 
          type: object
          description: JSON-объект в котором вы можете явно задать некоторые аргументы указанной функции. Остальные аргументы модель сгенерирует самостоятлеьно.
          properties: {}
    function_call_none_auto:
      type: string
      enum: 
        - auto
        - none
      description: Режим работы с функциями  
      example: auto  
  responses:
    UnauthorizedError:
      description: Unauthorized
    TokenExpired:
      description: Token has expired
    ModelNotFound:
      description: Model with id <model_id> not found
    NoSuchModel:
      description: No such Model
    InternalError:
      description: Internal Server Error
    BadRequestFormat:
      description: Bad request format
    TooManyRequests:
      description: Too many requests
    ValidationError:
      description: Validation error
  securitySchemes:
    Базовая аутентификация:
      description: |
        Базовая (Basic) аутентификация с помощью авторизационных данных — строки, полученной в результате кодирования в base64 идентификатора (Client ID) и клиентского ключа (Client Secret) API.

        Авторизационные данные передаются в заголовке `Authorization`, в запросе на [получение токена доступа](/ru/gigachat/api/reference/rest/post-token).

        <Admonition type="note">

        Как получить токен и авторизационные данные (Client Id и Client Secret) читайте в разделах [Быстрый старт для физических лиц](/ru/gigachat/individuals-quickstart) и [Быстрый старт для ИП и юридических лиц](/ru/gigachat/legal-quickstart).

        </Admonition>
      scheme: basic
      type: http
    Токен доступа:
      description: Аутентификация с помощью токена доступа. Используется во всех запросах к GigaChat API, кроме запроса на [получение токена доступа](/ru/gigachat/api/reference/rest/post-token).
      type: http
      scheme: bearer
      bearerFormat: JWT